home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / util / AbstractCollection.java next >
Encoding:
Java Source  |  1999-05-28  |  16.8 KB  |  458 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)AbstractCollection.java    1.11 98/09/30
  3.  *
  4.  * Copyright 1997, 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.util;
  16.  
  17. /**
  18.  * This class provides a skeletal implementation of the <tt>Collection</tt>
  19.  * interface, to minimize the effort required to implement this interface. <p>
  20.  *
  21.  * To implement an unmodifiable collection, the programmer needs only to
  22.  * extend this class and provide implementations for the <tt>iterator</tt> and
  23.  * <tt>size</tt> methods.  (The iterator returned by the <tt>iterator</tt>
  24.  * method must implement <tt>hasNext</tt> and <tt>next</tt>.)<p>
  25.  *
  26.  * To implement a modifiable collection, the programmer must additionally
  27.  * override this class's <tt>add</tt> method (which otherwise throws an
  28.  * <tt>UnsupportedOperationException</tt>), and the iterator returned by the
  29.  * <tt>iterator</tt> method must additionally implement its <tt>remove</tt>
  30.  * method.<p>
  31.  *
  32.  * The programmer should generally provide a void (no argument) and
  33.  * <tt>Collection</tt> constructor, as per the recommendation in the
  34.  * <tt>Collection</tt> interface specification.<p>
  35.  *
  36.  * The documentation for each non-abstract methods in this class describes its
  37.  * implementation in detail.  Each of these methods may be overridden if
  38.  * the collection being implemented admits a more efficient implementation.
  39.  *
  40.  * @author  Josh Bloch
  41.  * @version 1.11 09/30/98
  42.  * @see Collection
  43.  * @since JDK1.2
  44.  */
  45.  
  46. public abstract class AbstractCollection implements Collection {
  47.     /**
  48.      * Sole constructor.  (For invocation by subclass constructors, typically
  49.      * implicit.)
  50.      */
  51.     protected AbstractCollection() {
  52.     }
  53.  
  54.     // Query Operations
  55.  
  56.     /**
  57.      * Returns an iterator over the elements contained in this collection.
  58.      *
  59.      * @return an iterator over the elements contained in this collection.
  60.      */
  61.     public abstract Iterator iterator();
  62.  
  63.     /**
  64.      * Returns the number of elements in this collection.  If the collection
  65.      * contains more than <tt>Integer.MAX_VALUE</tt> elements, returns
  66.      * <tt>Integer.MAX_VALUE</tt>.
  67.      *
  68.      * @return the number of elements in this collection.
  69.      */
  70.     public abstract int size();
  71.  
  72.     /**
  73.      * Returns <tt>true</tt> if this collection contains no elements.<p>
  74.      *
  75.      * This implementation returns <tt>size() == 0</tt>.
  76.      *
  77.      * @return <tt>true</tt> if this collection contains no elements.
  78.      */
  79.     public boolean isEmpty() {
  80.     return size() == 0;
  81.     }
  82.  
  83.     /**
  84.      * Returns <tt>true</tt> if this collection contains the specified
  85.      * element.  More formally, returns <tt>true</tt> if and only if this
  86.      * collection contains at least one element <tt>e</tt> such that
  87.      * <tt>(o==null ? e==null : o.equals(e))</tt>.<p>
  88.      *
  89.      * This implementation iterates over the elements in the collection,
  90.      * checking each element in turn for equality with the specified element.
  91.      *
  92.      * @param o object to be checked for containment in this collection.
  93.      * @return <tt>true</tt> if this collection contains the specified element.
  94.      */
  95.     public boolean contains(Object o) {
  96.     Iterator e = iterator();
  97.     if (o==null) {
  98.         while (e.hasNext())
  99.         if (e.next()==null)
  100.             return true;
  101.     } else {
  102.         while (e.hasNext())
  103.         if (o.equals(e.next()))
  104.             return true;
  105.     }
  106.     return false;
  107.     }
  108.  
  109.     /**
  110.      * Returns an array containing all of the elements in this collection.  If
  111.      * the collection makes any guarantees as to what order its elements are
  112.      * returned by its iterator, this method must return the elements in the
  113.      * same order.  The returned array will be "safe" in that no references to
  114.      * it are maintained by the collection.  (In other words, this method must
  115.      * allocate a new array even if the collection is backed by an Array).
  116.      * The caller is thus free to modify the returned array.<p>
  117.      *
  118.      * This implementation allocates the array to be returned, and iterates
  119.      * over the elements in the collection, storing each object reference in
  120.      * the next consecutive element of the array, starting with element 0.
  121.      *
  122.      * @return an array containing all of the elements in this collection.
  123.      */
  124.     public Object[] toArray() {
  125.     Object[] result = new Object[size()];
  126.     Iterator e = iterator();
  127.     for (int i=0; e.hasNext(); i++)
  128.         result[i] = e.next();
  129.     return result;
  130.     }
  131.  
  132.     /**
  133.      * Returns an array with a runtime type is that of the specified array and
  134.      * that contains all of the elements in this collection.  If the
  135.      * collection fits in the specified array, it is returned therein.
  136.      * Otherwise, a new array is allocated with the runtime type of the
  137.      * specified array and the size of this collection.<p>
  138.      *
  139.      * If the collection fits in the specified array with room to spare (i.e.,
  140.      * the array has more elements than the collection), the element in the
  141.      * array immediately following the end of the collection is set to
  142.      * <tt>null</tt>.  This is useful in determining the length of the
  143.      * collection <i>only</i> if the caller knows that the collection does
  144.      * not contain any <tt>null</tt> elements.)<p>
  145.      *
  146.      * If this collection makes any guarantees as to what order its elements
  147.      * are returned by its iterator, this method must return the elements in
  148.      * the same order. <p>
  149.      *
  150.      * This implementation checks if the array is large enough to contain the
  151.      * collection; if not, it allocates a new array of the correct size and
  152.      * type (using reflection).  Then, it iterates over the collection,
  153.      * storing each object reference in the next consecutive element of the
  154.      * array, starting with element 0.  If the array is larger than the
  155.      * collection, a <tt>null</tt> is stored in the first location after the
  156.      * end of the collection.
  157.      *
  158.      * @param  a the array into which the elements of the collection are to
  159.      *            be stored, if it is big enough; otherwise, a new array of the
  160.      *            same runtime type is allocated for this purpose.
  161.      * @return an array containing the elements of the collection.
  162.      * 
  163.      * @throws NullPointerException if the specified array is <tt>null</tt>.
  164.      * 
  165.      * @throws ArrayStoreException if the runtime type of the specified array
  166.      *         is not a supertype of the runtime type of every element in this
  167.      *         collection.
  168.      */
  169.     public Object[] toArray(Object a[]) {
  170.         int size = size();
  171.         if (a.length < size)
  172.             a = (Object[])java.lang.reflect.Array.newInstance(
  173.                                   a.getClass().getComponentType(), size);
  174.  
  175.         Iterator it=iterator();
  176.         for (int i=0; i<size; i++)
  177.             a[i] = it.next();
  178.  
  179.         if (a.length > size)
  180.             a[size] = null;
  181.  
  182.         return a;
  183.     }
  184.  
  185.     // Modification Operations
  186.  
  187.     /**
  188.      * Ensures that this collection contains the specified element (optional
  189.      * operation).  Returns <tt>true</tt> if the collection changed as a
  190.      * result of the call.  (Returns <tt>false</tt> if this collection does
  191.      * not permit duplicates and already contains the specified element.)
  192.      * Collections that support this operation may place limitations on what
  193.      * elements may be added to the collection.  In particular, some
  194.      * collections will refuse to add <tt>null</tt> elements, and others will
  195.      * impose restrictions on the type of elements that may be added.
  196.      * Collection classes should clearly specify in their documentation any
  197.      * restrictions on what elements may be added.<p>
  198.      *
  199.      * This implementation always throws an
  200.      * <tt>UnsupportedOperationException</tt>.
  201.      *
  202.      * @param o element whose presence in this collection is to be ensured.
  203.      * @return <tt>true</tt> if the collection changed as a result of the call.
  204.      * 
  205.      * @throws UnsupportedOperationException if the <tt>add</tt> method is not
  206.      *          supported by this collection.
  207.      * 
  208.      * @throws NullPointerException if this collection does not permit
  209.      *           <tt>null</tt> elements, and the specified element is
  210.      *           <tt>null</tt>.
  211.      * 
  212.      * @throws ClassCastException if the class of the specified element
  213.      *           prevents it from being added to this collection.
  214.      * 
  215.      * @throws IllegalArgumentException if some aspect of this element
  216.      *            prevents it from being added to this collection.
  217.      */
  218.     public boolean add(Object o) {
  219.     throw new UnsupportedOperationException();
  220.     }
  221.  
  222.     /**
  223.      * Removes a single instance of the specified element from this
  224.      * collection, if it is present (optional operation).  More formally,
  225.      * removes an element <tt>e</tt> such that <tt>(o==null ? e==null :
  226.      * o.equals(e))</tt>, if the collection contains one or more such
  227.      * elements.  Returns <tt>true</tt> if the collection contained the
  228.      * specified element (or equivalently, if the collection changed as a
  229.      * result of the call).<p>
  230.      *
  231.      * This implementation iterates over the collection looking for the
  232.      * specified element.  If it finds the element, it removes the element
  233.      * from the collection using the iterator's remove method.<p>
  234.      *
  235.      * Note that this implementation throws an
  236.      * <tt>UnsupportedOperationException</tt> if the iterator returned by this
  237.      * collection's iterator method does not implement the <tt>remove</tt>
  238.      * method.
  239.      *
  240.      * @param o element to be removed from this collection, if present.
  241.      * @return <tt>true</tt> if the collection contained the specified
  242.      *         element.
  243.      * 
  244.      * @throws UnsupportedOperationException if the <tt>remove</tt> method is
  245.      *           not supported by this collection.
  246.      */
  247.     public boolean remove(Object o) {
  248.     Iterator e = iterator();
  249.     if (o==null) {
  250.         while (e.hasNext()) {
  251.         if (e.next()==null) {
  252.             e.remove();
  253.             return true;
  254.         }
  255.         }
  256.     } else {
  257.         while (e.hasNext()) {
  258.         if (o.equals(e.next())) {
  259.             e.remove();
  260.             return true;
  261.         }
  262.         }
  263.     }
  264.     return false;
  265.     }
  266.  
  267.  
  268.     // Bulk Operations
  269.  
  270.     /**
  271.      * Returns <tt>true</tt> if this collection contains all of the elements
  272.      * in the specified collection. <p>
  273.      *
  274.      * This implementation iterates over the specified collection, checking
  275.      * each element returned by the iterator in turn to see if it's
  276.      * contained in this collection.  If all elements are so contained
  277.      * <tt>true</tt> is returned, otherwise <tt>false</tt>.
  278.      *
  279.      * @param c collection to be checked for containment in this collection.
  280.      * @return <tt>true</tt> if this collection contains all of the elements
  281.      *            in the specified collection.
  282.      * 
  283.      * @see #contains(Object)
  284.      */
  285.     public boolean containsAll(Collection c) {
  286.     Iterator e = c.iterator();
  287.     while (e.hasNext())
  288.         if(!contains(e.next()))
  289.         return false;
  290.  
  291.     return true;
  292.     }
  293.  
  294.     /**
  295.      * Adds all of the elements in the specified collection to this collection
  296.      * (optional operation).  The behavior of this operation is undefined if
  297.      * the specified collection is modified while the operation is in
  298.      * progress.  (This implies that the behavior of this call is undefined if
  299.      * the specified collection is this collection, and this collection is
  300.      * nonempty.) <p>
  301.      *
  302.      * This implementation iterates over the specified collection, and adds
  303.      * each object returned by the iterator to this collection, in turn.<p>
  304.      *
  305.      * Note that this implementation will throw an
  306.      * <tt>UnsupportedOperationException</tt> unless <tt>add</tt> is
  307.      * overridden.
  308.      *
  309.      * @param c collection whose elements are to be added to this collection.
  310.      * @return <tt>true</tt> if this collection changed as a result of the
  311.      * call.
  312.      * @throws UnsupportedOperationException if the <tt>addAll</tt> method is
  313.      *           not supported by this collection.
  314.      * 
  315.      * @see #add(Object)
  316.      */
  317.     public boolean addAll(Collection c) {
  318.     boolean modified = false;
  319.     Iterator e = c.iterator();
  320.     while (e.hasNext()) {
  321.         if(add(e.next()))
  322.         modified = true;
  323.     }
  324.     return modified;
  325.     }
  326.  
  327.     /**
  328.      * Removes from this collection all of its elements that are contained in
  329.      * the specified collection (optional operation). <p>
  330.      *
  331.      * This implementation iterates over this collection, checking each
  332.      * element returned by the iterator in turn to see if it's contained
  333.      * in the specified collection.  If it's so contained, it's removed from
  334.      * this collection with the iterator's <tt>remove</tt> method.<p>
  335.      *
  336.      * Note that this implementation will throw an
  337.      * <tt>UnsupportedOperationException</tt> if the iterator returned by the
  338.      * <tt>iterator</tt> method does not implement the <tt>remove</tt> method.
  339.      *
  340.      * @param c elements to be removed from this collection.
  341.      * @return <tt>true</tt> if this collection changed as a result of the
  342.      * call.
  343.      * 
  344.      * @throws    UnsupportedOperationException removeAll is not supported
  345.      *           by this collection.
  346.      * 
  347.      * @see #remove(Object)
  348.      * @see #contains(Object)
  349.      */
  350.     public boolean removeAll(Collection c) {
  351.     boolean modified = false;
  352.     Iterator e = iterator();
  353.     while (e.hasNext()) {
  354.         if(c.contains(e.next())) {
  355.         e.remove();
  356.         modified = true;
  357.         }
  358.     }
  359.     return modified;
  360.     }
  361.  
  362.     /**
  363.      * Retains only the elements in this collection that are contained in the
  364.      * specified collection (optional operation).  In other words, removes
  365.      * from this collection all of its elements that are not contained in the
  366.      * specified collection. <p>
  367.      *
  368.      * This implementation iterates over this collection, checking each
  369.      * element returned by the iterator in turn to see if it's contained
  370.      * in the specified collection.  If it's not so contained, it's removed
  371.      * from this collection with the iterator's <tt>remove</tt> method.<p>
  372.      *
  373.      * Note that this implementation will throw an
  374.      * <tt>UnsupportedOperationException</tt> if the iterator returned by the
  375.      * <tt>iterator</tt> method does not implement the remove method.
  376.      *
  377.      * @return <tt>true</tt> if this collection changed as a result of the
  378.      *         call.
  379.      * 
  380.      * @throws UnsupportedOperationException if the <tt>retainAll</tt> method
  381.      *           is not supported by this collection.
  382.      * 
  383.      * @see #remove(Object)
  384.      * @see #contains(Object)
  385.      */
  386.     public boolean retainAll(Collection c) {
  387.     boolean modified = false;
  388.     Iterator e = iterator();
  389.     while (e.hasNext()) {
  390.         if(!c.contains(e.next())) {
  391.         e.remove();
  392.         modified = true;
  393.         }
  394.     }
  395.     return modified;
  396.     }
  397.  
  398.     /**
  399.      * Removes all of the elements from this collection (optional operation).
  400.      * The collection will be empty after this call returns (unless it throws
  401.      * an exception).<p>
  402.      *
  403.      * This implementation iterates over this collection, removing each
  404.      * element using the <tt>Iterator.remove</tt> operation.  Most
  405.      * implementations will probably choose to override this method for
  406.      * efficiency.<p>
  407.      *
  408.      * Note that this implementation will throw an
  409.      * <tt>UnsupportedOperationException</tt> if the iterator returned by this
  410.      * collection's <tt>iterator</tt> method does not implement the
  411.      * <tt>remove</tt> method.
  412.      *
  413.      * @throws UnsupportedOperationException if the <tt>remove</tt> method is
  414.      *           not supported by this collection.
  415.      */
  416.     public void clear() {
  417.     Iterator e = iterator();
  418.     while (e.hasNext()) {
  419.         e.next();
  420.         e.remove();
  421.     }
  422.     }
  423.  
  424.  
  425.     //  String conversion
  426.  
  427.     /**
  428.      * Returns a string representation of this collection.  The string
  429.      * representation consists of a list of the collection's elements in the
  430.      * order they are returned by its iterator, enclosed in square brackets
  431.      * (<tt>"[]"</tt>).  Adjacent elements are separated by the characters
  432.      * <tt>", "</tt> (comma and space).  Elements are converted to strings as
  433.      * by <tt>String.valueOf(Object)</tt>.<p>
  434.      *
  435.      * This implementation creates an empty string buffer, appends a left
  436.      * square bracket, and iterates over the collection appending the string
  437.      * representation of each element in turn.  After appending each element
  438.      * except the last, the string <tt>", "</tt> is appended.  Finally a right
  439.      * bracket is appended.  A string is obtained from the string buffer, and
  440.      * returned.
  441.      * 
  442.      * @return a string representation of this collection.
  443.      */
  444.     public String toString() {
  445.     StringBuffer buf = new StringBuffer();
  446.     Iterator e = iterator();
  447.     buf.append("[");
  448.     int maxIndex = size() - 1;
  449.     for (int i = 0; i <= maxIndex; i++) {
  450.         buf.append(String.valueOf(e.next()));
  451.         if (i < maxIndex)
  452.         buf.append(", ");
  453.     }
  454.     buf.append("]");
  455.     return buf.toString();
  456.     }
  457. }
  458.